Event and Exception

Event and Exception

There are 2 types of SDK events: normal notification events and exception alarm events.

• The normal notification events are sent when frame grabbers or cameras are in normal condition. Based on event generation conditions, operations to report events vary.

  • Some events are only triggered when cameras or cameras connected to frame grabbers start grabbing images. To report these events to the program, you should first subscribe to and enable the specified events, and call MV_CC_StartGrabbing() to start grabbing images.

  • Other events can be reported to the program without grabbing images. To report these events to the program, you should subscribe to and enable the specified events.

• The exception alarm events are sent when errors occur in the SDK and can be acquired directly from the SDK. These events are to notify users of exceptions during frame grabber or camera running (e.g., camera offline) so that users can perform troubleshooting in time.

  When cameras or frame grabbers are turned on, custom exception alarm event processing function can be registered. After registration, when exception alarm is generated, the device will automatically execute custom exception alarm processing function.

Event Acquisition

The normal notification event handling process: subscribe to event, enable event, get event, disable event, and unsubscribe from event.

Note

To get the normal notification events, configure the EventControl feature of the frame grabber / camera via the client.

• For more details of camera configuration, refer to the client user manual.
• Frame grabber events can be configured via the frame grabber event configuration tool.

1. Subscribe to Event: Call MV_CC_RegisterEventCallBackEx() to subscribe to a specified event. Pass the event name strEventName when calling this API.

2. Enable Event: Call MV_CC_EventNotificationOn() to enable the specified event.

3. Get Event: When the frame grabber or camera generates an event, the SDK will trigger the corresponding event callback function and push the event information to users. The pushed event information usually contains key information such as the event name, event ID, and timestamp, but not necessarily others such as frame No. and event data. Information contained in different events might vary, and the actual condition shall prevail.

   Attention

   Avoid calling the event callback function for operations that require more time, otherwise the subsequent event information push will be blocked.
   

4. Close Event: Call MV_CC_EventNotificationOff() to close the specified event.

5. Unsubscribe from Event: Call MV_CC_RegisterEventCallBackEx() to unsubscribe from the event. Pass the event name strEventName when calling this API, and set the event callback pointer cbEvent to NULL. After a successful calling, you can unsubscribe from the specified event.

The following sample codes show the process of camera exposure end event.

stEventInfo = POINTER(MV_EVENT_OUT_INFO)
EventInfoCallBack = winfun_ctype(None, stEventInfo, c_void_p)

def event_callback(pEventInfo, pUser):
    stPEventInfo = cast(pEventInfo, POINTER(MV_EVENT_OUT_INFO)).contents
    nBlockId = stPEventInfo.nBlockIdHigh
    nBlockId = (nBlockId << 32) + stPEventInfo.nBlockIdLow
    nTimestamp = stPEventInfo.nTimestampHigh
    nTimestamp = (nTimestamp << 32) + stPEventInfo.nTimestampLow
    if stPEventInfo:
        print ("EventName[%s], EventId[%u], BlockId[%d], Timestamp[%d]" % (stPEventInfo.EventName.decode('UTF-8'),
                                                                           stPEventInfo.nEventID, nBlockId, nTimestamp))

CALL_BACK_FUN = EventInfoCallBack(event_callback)
if __name__ == "__main__":

    # Initialize SDK resources
    MvCamera.MV_CC_Initialize()

    # Enumerate devices and create camera instance


    # Turn on the device
    ret = cam.MV_CC_OpenDevice(MV_ACCESS_Exclusive, 0)
    if ret != 0:
        print ("open device fail! ret[0x%x]" % ret)
        sys.exit()


    # Enable Event by setting event selector as ExposureEnd
    ret = cam.MV_CC_EventNotificationOn("ExposureEnd")
    if ret != 0:
        print ("Set Event Notification On fail! ret[0x%x]" % ret)
        sys.exit()

    # Register an event callback
    ret = cam.MV_CC_RegisterEventCallBackEx("ExposureEnd", CALL_BACK_FUN,None)
    if ret != 0:
        print ("register event callback fail! ret [0x%x]" % ret)
        sys.exit()

    # Start grabbing images
    cam.MV_CC_StartGrabbing()
    if ret != 0:
        print ("start grabbing fail! ret[0x%x]" % ret)
        sys.exit()

    print ("press a key to stop grabbing.")
    press_any_key_exit()

    # Stop grabbing images
    ret = cam.MV_CC_StopGrabbing()
    if ret != 0:
        print ("stop grabbing fail! ret[0x%x]" % ret)
        sys.exit()

    # Turn off the device
    ret = cam.MV_CC_CloseDevice()
    if ret != 0:
        print ("close deivce fail! ret[0x%x]" % ret)
        sys.exit()

    # Destroy the handle
    ret = cam.MV_CC_DestroyHandle()
    if ret != 0:
        print ("destroy handle fail! ret[0x%x]" % ret)
        sys.exit()

    # Release SDK resources
    MvCamera.MV_CC_Finalize()

Note

For sample code of enumerating devices and creating camera instance, refer to the chapter Camera Initialization.

The following sample codes show the process of frame grabber frame start event.

# Event callback function
stEventInfo = POINTER(MV_EVENT_OUT_INFO)
EventInfoCallBack = winfun_ctype(None, stEventInfo, c_void_p)


def event_callback(pEventInfo, pUser):
    stPEventInfo = cast(pEventInfo, POINTER(MV_EVENT_OUT_INFO)).contents
    nBlockId = stPEventInfo.nBlockIdHigh
    nBlockId = (nBlockId << 32) + stPEventInfo.nBlockIdLow
    nTimestamp = stPEventInfo.nTimestampHigh
    nTimestamp = (nTimestamp << 32) + stPEventInfo.nTimestampLow
    if stPEventInfo:
        print("EventName[%s], EventId[%u], BlockId[%d], Timestamp[%d]" % (stPEventInfo.EventName.decode('UTF-8'),
                                                                          stPEventInfo.nEventID, nBlockId, nTimestamp))

EVENT_CALL_BACK_FUN = EventInfoCallBack(event_callback)


if __name__ == "__main__":
    try:
        # Initialize SDK resources
        MvCamera.MV_CC_Initialize()

        interfaceList = MV_INTERFACE_INFO_LIST()
        transportLayerType = MV_GIGE_INTERFACE | MV_CAMERALINK_INTERFACE | MV_CXP_INTERFACE | MV_XOF_INTERFACE

        # Enumerate frame grabbers
        ret = MvCamera.MV_CC_EnumInterfaces(transportLayerType, interfaceList)
        if ret != 0:
            print("enum interfaces fail! ret[0x%x]" % ret)
            sys.exit()

        if interfaceList.nInterfaceNum == 0:
            print("find no interface!")
            sys.exit()

        print("Find %d interfaces!" % interfaceList.nInterfaceNum)
        print_interface_info(interfaceList)

        nInterfaceIndex = input("please input the number of the interface to connect:")

        if int(nInterfaceIndex) >= interfaceList.nInterfaceNum:
            print("input error!")
            sys.exit()

        # Create a camera instance
        cam_instance = MvCamera()
        interface_instance = MvCamera()

        # Select the frame grabber, and create a handle
        curInterface = cast(interfaceList.pInterfaceInfos[int(nInterfaceIndex)], POINTER(MV_INTERFACE_INFO)).contents

        ret = interface_instance.MV_CC_CreateInterface(curInterface)
        if ret != 0:
            raise Exception("create interface handle fail! ret[0x%x]" % ret)

        # Turn on the frame grabber
        ret = interface_instance.MV_CC_OpenInterface()
        if ret != 0:
            raise Exception("open interface fail! ret[0x%x]" % ret)
        else:
            print("open interface success")

        # Enable the ReceiveImageFrameStart0 event of frame grabber
        ret = interface_instance.MV_CC_EventNotificationOn("ReceiveImageFrameStart0")
        if ret != 0:
            raise Exception("Set interface event notification on fail! ret[0x%x]" % ret)

        # Register an event callback of frame grabber
        ret = interface_instance.MV_CC_RegisterEventCallBackEx("ReceiveImageFrameStart0", EVENT_CALL_BACK_FUN, None)
        if ret != 0:
            raise Exception("register event callback fail! ret [0x%x]" % ret)


        # Turn off the frame grabber
        interface_instance.MV_CC_CloseInterface()

        # Destroy frame grabber handle
        interface_instance.MV_CC_DestroyInterface()
    except Exception as e:
        print(e)
        cam_instance.MV_CC_CloseDevice()
        cam_instance.MV_CC_DestroyHandle()
        interface_instance.MV_CC_CloseInterface()
        interface_instance.MV_CC_DestroyInterface()

    finally:
        # Release SDK resources
        MvCamera.MV_CC_Finalize()

Note

For sample code of enumerating devices and creating frame grabber instance, refer to the chapter Frame Grabber Initialization.

Exception Alarm Event

Exception alarm events can be obtained directly from the SDK. The handling process of these events: register event, get event, and unregister from event.

1. Register Event: Call MV_CC_RegisterExceptionCallBack() to register exception event. Exception will be reported to SDK.

2. Get Event: When exception occurs in SDK, exception callback function will be triggered, pushing exception alarm event to the user.

   Attention

   Avoid calling the event callback function for operations that require more time, otherwise the subsequent event information push will be blocked.

3. Unregister from Event: Call MV_CC_RegisterExceptionCallBack() to unregister from exception alarm event. When exception callback function is NULL, you can unsubscribe from the exception alarm event of frame grabbers or the camera instance.

   The following sample codes show how to subscribe to, handle, and unsubscribe from exception alarm event.

   ExceptionInfoCallBack = winfun_ctype(None, c_uint, c_void_p)
   def exception_callback(MsgType, pUser):
       print ("exception_callback Recv MsgType[%d] " % (MsgType))
   
   CALL_BACK_FUN = ExceptionInfoCallBack(exception_callback)
   
   
   
   if __name__ == "__main__":
       # Initialize SDK resources
       MvCamera.MV_CC_Initialize()
       
   
       # Enumerate cameras
   
   
       # Create the camera instance
       cam = MvCamera()
   
       # Select a device, and create a handle
       stDeviceList = cast(deviceList.pDeviceInfo[int(nConnectionNum)], POINTER(MV_CC_DEVICE_INFO)).contents
   
       ret = cam.MV_CC_CreateHandle(stDeviceList)
       if ret != 0:
           print ("create handle fail! ret[0x%x]" % ret)
           sys.exit()
   
       # Turn on the device
       ret = cam.MV_CC_OpenDevice()
       #ret = cam.MV_CC_OpenDevice(MV_ACCESS_Exclusive, 0)
       if ret != 0:
           print ("open device fail! ret[0x%x]" % ret)
           sys.exit()
       
   
       # Register an event callback
       ret = cam.MV_CC_RegisterExceptionCallBack(CALL_BACK_FUN,None)
       if ret != 0:
           print ("register event callback fail! ret [0x%x]" % ret)
           sys.exit()
   
       # Start grabbing images
       print ("press a key to stop grabbing.")
       press_any_key_exit()
   
       print ("press a key to stop grabbing.")
       msvcrt.getch()
   
       # Stop grabbing images
       ret = cam.MV_CC_StopGrabbing()
       if ret != 0:
           print ("stop grabbing fail! ret[0x%x]" % ret)
           sys.exit()
   
       # Turn off the device
       ret = cam.MV_CC_CloseDevice()
       if ret != 0:
           print ("close deivce fail! ret[0x%x]" % ret)
           sys.exit()
   
       # Destroy the handle
       ret = cam.MV_CC_DestroyHandle()
       if ret != 0:
           print ("destroy handle fail! ret[0x%x]" % ret)
           sys.exit()
   
       # Release SDK resources
       MvCamera.MV_CC_Finalize()

   Note

   For sample code of enumerating devices and creating camera instance, refer to the chapter Camera Initialization.

Adjust Event Buffer

Event generated by GigE cameras uses socket buffer area, and there is no need to configure extra buffer area. Event generated by U3V devices is reported via event endpoint or link. There are 5 buffer nodes by default for receiving event in SDK. Slow software processing in the upper layer and high frequency event-reporting may result in insufficient SDK buffer, leading to event loss. You can edit the number of event buffer nodes of U3V camera in SDK by calling MV_USB_SetEventNodeNum().

# Set the number of event buffer areas of USB3 vision devices in SDK
EventNodeNum = 5
ret = cam.MV_USB_SetEventNodeNum(EventNodeNum)
if ret != 0:
    print ("MV_USB_SetEventNodeNum fail! ret[0x%x]" % ret)
    sys.exit()

Previous: Parameter Configuration

Next: Image Acquisition